/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.dubbo.config.annotation;


import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import static org.apache.dubbo.common.constants.CommonConstants.DEFAULT_LOADBALANCE;
import static org.apache.dubbo.common.constants.CommonConstants.DEFAULT_RETRIES;

/**
 * Class-level annotation used for declaring Dubbo service
 *
 * @since 2.7.7
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
@Inherited
public @interface DubboService {

    /**
     * Interface class, default value is void.class
     */
    Class<?> interfaceClass() default void.class;

    /**
     * Interface class name, default value is empty string
     */
    String interfaceName() default "";

    /**
     * Service version, default value is empty string
     * 服务的版本号，默认是空
     */
    String version() default "";

    /**
     * Service group, default value is empty string
     * 服务所属分组，默认是空。当一个接口有多个实现，可以用分组区分
     */
    String group() default "";

    /**
     * Service path, default value is empty string
     * 服务路径，默认值是空。
     */
    String path() default "";

    /**
     * Whether to export service, default value is true
     * 是否导出服务，默认值是true
     */
    boolean export() default true;

    /**
     * Service token, default value is false
     * 令牌验证，为空表示不开启，如果为true，表示随机生成动态令牌，否则使用静态令牌，令牌的作用是防止消费者绕过注册中心直接访问，
     * 保证注册中心的授权功能有效，如果使用点对点调用，需关闭令牌功能
     */
    String token() default "";

    /**
     * Whether the service is deprecated, default value is false
     * 服务是否过时，如果设为true，消费方引用时将打印服务过时警告error日志
     */
    boolean deprecated() default false;

    /**
     * Whether the service is dynamic, default value is true
     * 服务是否动态注册，如果设为false，注册后将显示后disable状态，需人工启用，并且服务提供者停止时，也不会自动取消册，需人工禁用。
     */
    boolean dynamic() default true;

    /**
     * Access log for the service, default value is ""
     * 设为true，将向logger中输出访问日志，也可填写访问日志文件路径，直接把访问日志输出到指定文件
     */
    String accesslog() default "";

    /**
     * Maximum concurrent executes for the service, default value is 0 - no limits
     * 服务提供者每服务每方法最大可并行执行请求数。默认是0，表示没有限制
     */
    int executes() default 0;

    /**
     * Whether to register the service to register center, default value is true
     * 该协议的服务是否注册到注册中心
     */
    boolean register() default true;

    /**
     * Service weight value, default value is 0
     * 服务权重
     */
    int weight() default 0;

    /**
     * Service doc, default value is ""
     * 服务文档URL
     */
    String document() default "";

    /**
     * Delay time for service registration, default value is 0
     * 延迟注册服务时间(毫秒) ，设为0时，表示延迟到Spring容器初始化完成时暴露服务
     */
    int delay() default 0;

    /**
     * 设为true，表示使用缺省代理类名，即：接口名 + Local后缀，已废弃，请使用stub
     * @see DubboService#stub()
     * @deprecated
     */
    String local() default "";

    /**
     * Service stub name, use interface name + Local if not set
     * 设为true，表示使用缺省代理类名，即：接口名 + Stub后缀，服务接口客户端本地代理类名，用于在客户端执行本地逻辑，如本地缓存等，
     * 该本地代理类的构造函数必须允许传入远程代理对象，构造函数如：public XxxServiceStub(XxxService xxxService)
     */
    String stub() default "";

    /**
     * Cluster strategy, legal values include: failover, failfast, failsafe, failback, forking
     * 集群方式，可选：failover/failfast/failsafe/failback/forking
     */
    String cluster() default "";

    /**
     * How the proxy is generated, legal values include: jdk, javassist
     * 生成动态代理方式，可选：jdk/javassist
     */
    String proxy() default "";

    /**
     * Maximum connections service provider can accept, default value is 0 - connection is shared
     * 对每个提供者的最大连接数，rmi、http、hessian等短连接协议表示限制连接数，dubbo等长连接协表示建立的长连接个数
     */
    int connections() default 0;

    /**
     * The callback instance limit peer connection
     * <p>
     * see org.apache.dubbo.rpc.Constants#DEFAULT_CALLBACK_INSTANCES
     */
    int callbacks() default org.apache.dubbo.common.constants.CommonConstants.DEFAULT_CALLBACK_INSTANCES;

    /**
     * Callback method name when connected, default value is empty string
     */
    String onconnect() default "";

    /**
     * Callback method name when disconnected, default value is empty string
     */
    String ondisconnect() default "";

    /**
     * Service owner, default value is empty string
     * 服务负责人，用于服务治理，请填写负责人公司邮箱前缀
     */
    String owner() default "";

    /**
     * Service layer, default value is empty string
     * 服务提供者所在的分层。如：biz、dao、intl:web、china:acton。
     */
    String layer() default "";

    /**
     * Service invocation retry times
     * 远程服务调用重试次数，不包括第一次调用，不需要重试请设为0
     *
     * @see org.apache.dubbo.common.constants.CommonConstants#DEFAULT_RETRIES
     */
    int retries() default DEFAULT_RETRIES;

    /**
     * Load balance strategy, legal values include: random, roundrobin, leastactive
     * 负载均衡策略，默认值：random，可选值：random,roundrobin,leastactive，分别表示：随机，轮询，最少活跃调用
     * @see org.apache.dubbo.common.constants.CommonConstants#DEFAULT_LOADBALANCE
     */
    String loadbalance() default DEFAULT_LOADBALANCE;

    /**
     * Whether to enable async invocation, default value is false
     * 是否缺省异步执行，不可靠异步，只是忽略返回值，不阻塞执行线程
     */
    boolean async() default false;

    /**
     * Maximum active requests allowed, default value is 0
     */
    int actives() default 0;

    /**
     * Whether the async request has already been sent, the default value is false
     */
    boolean sent() default false;

    /**
     * Service mock name, use interface name + Mock if not set
     * 设为true，表示使用缺省Mock类名，即：接口名 + Mock后缀，服务接口调用失败Mock实现类，该Mock类必须有一个无参构造函数，
     * 与Local的区别在于，Local总是被执行，而Mock只在出现非业务异常(比如超时，网络异常等)时执行，Local在远程调用之前执行，
     * Mock在远程调用后执行。
     */
    String mock() default "";

    /**
     * Whether to use JSR303 validation, legal values are: true, false
     */
    String validation() default "";

    /**
     * Timeout value for service invocation, default value is 0
     * 远程服务调用超时时间(毫秒)
     */
    int timeout() default 0;

    /**
     * Specify cache implementation for service invocation, legal values include: lru, threadlocal, jcache
     */
    String cache() default "";

    /**
     * Filters for service invocation
     * 服务提供方远程调用过程拦截器名称，多个名称用逗号分隔
     * @see Filter
     */
    String[] filter() default {};

    /**
     * Listeners for service exporting and unexporting
     * 服务提供方导出服务监听器名称，多个名称用逗号分隔
     * @see ExporterListener
     */
    String[] listener() default {};

    /**
     * Customized parameter key-value pair, for example: {key1, value1, key2, value2}
     */
    String[] parameters() default {};

    /**
     * Application spring bean name
     */
    String application() default "";

    /**
     * Module spring bean name
     */
    String module() default "";

    /**
     * Provider spring bean name
     * 指定provider，值为<dubbo:provider>的id属性
     */
    String provider() default "";

    /**
     * Protocol spring bean names
     * 使用指定的协议暴露服务，在多协议时使用，值为<dubbo:protocol>的id属性，多个协议ID用逗号分隔
     */
    String[] protocol() default {};

    /**
     * Monitor spring bean name
     */
    String monitor() default "";

    /**
     * Registry spring bean name
     * 向指定注册中心注册，在多个注册中心时使用，值为<dubbo:registry>的id属性，多个注册中心ID用逗号分隔，
     * 如果不想将该服务注册到任何registry，可将值设为N/A
     */
    String[] registry() default {};

    /**
     * Service tag name
     */
    String tag() default "";

    /**
     * methods support
     *
     * @return
     */
    Method[] methods() default {};
}
